created by Aha00aAha00a at 2026-11-15
last modified by Aha00aAha00a at 2026-11-15
revision: 1

예시 API 문서

개발 문서는 고치는 사람이 많고 자주 바뀝니다. 위키에 두면 바뀐 내력이 남고, 누가 언제 무엇을 바꿨는지 RecentChanges 와 이력에서 보입니다. API 하나에 페이지 하나를 두고, 프로젝트 홈에서 링크합니다. 아래 내용은 예시 프로젝트 홈 의 사내 예약 시스템을 두고 지어낸 예시입니다.

1. 요약

회의실을 예약한다. 같은 방, 겹치는 시간에 이미 예약이 있으면 거절한다.

항목

값

메서드

POST

경로

/api/reservations

인증

로그인한 사원 (세션 쿠키)

2. 요청

curl -X POST https://booking.example.com/api/reservations \
  -H 'Content-Type: application/json' \
  -d '{"room": "3F-A", "start": "2026-12-01T10:00", "end": "2026-12-01T11:00", "title": "주간 회의"}'

필드

형식

필수

설명

room

문자열

예

회의실 이름. 목록은 GET /api/rooms

start

시각

예

시작 시각. 30분 단위

end

시각

예

끝 시각. start 보다 뒤

title

문자열

아니오

달력에 보일 제목. 100자까지

3. 응답

성공하면 201 과 만든 예약을 돌려준다.

{
  "id": 1042,
  "room": "3F-A",
  "start": "2026-12-01T10:00",
  "end": "2026-12-01T11:00",
  "title": "주간 회의"
}

상태

뜻

본문

201

만들었다

예약

400

필드가 빠졌거나 시각이 30분 단위가 아니다

무엇이 틀렸는지

401

로그인하지 않았다

없음

409

같은 방, 겹치는 시간에 예약이 있다

겹친 예약의 id

4. 흐름

sequenceDiagram participant 사용자 participant 웹 as 웹 서버 participant DB as 데이터베이스 사용자->>웹: POST /api/reservations 웹->>DB: 겹치는 예약이 있나 alt 있다 웹-->>사용자: 409 else 없다 웹->>DB: 예약 저장 웹-->>사용자: 201 end

5. 바뀐 내력

  • 2026-11-02 title 을 받기 시작했다. 없으면 «(제목 없음)» 으로 보인다.
  • 2026-10-21 처음 만들었다.

6. 이렇게 쓰면 좋습니다

  • API 하나에 페이지 하나. 프로젝트 홈의 목록에서 링크하면, 이 페이지 아래의 «이 문서를 가리키는 문서» 에 프로젝트 홈이 보입니다.
  • 요청과 응답은 코드 구간으로. #!Vim 뒤에 언어 이름을 적으면 색이 입혀지고, 복사 단추가 붙습니다(InterpreterVim).
  • 필드와 상태는 표로. 머리글을 눌러 정렬하고, 칸에 적어 걸러 봅니다(InterpreterTable).
  • 흐름은 그림으로. Mermaid 의 sequenceDiagram 으로 누가 누구에게 무엇을 보내는지 그립니다(InterpreterMermaid).
  • 왜 그렇게 했는지는 접어서. 읽는 사람 대부분에게는 필요 없지만, 고치는 사람에게는 꼭 필요합니다(InterpreterFold).

8. See Also

8.2. Similar Pages

Similar pages by cosine similarity. Words after page name are term frequency.

  • 31.30% 예시 프로젝트 홈 예시(7:6), api(8:1), 프로젝트(5:2), interpreter(4:1), 같은(4:1), 사용자(4:1), 예약(3:2), 함께(2:3), 회의록(2:3), 페이지(3:1)

8.3. Adjacent Pages

≤ 32
all
1.0x
1.0x
80
-120
ON
0/0
0/0
0.00
0
0 / 0
1.00x